Summary

A proxy engine that:

• receives client HTTP requests
• selects an upstream via configured routes
• forwards requests over pooled connections
• parses upstream responses
• relays them back to clients

What was built

Adds the core proxy engine: receive a client HTTP request, select an upstream service via configured route, forward the request over a pooled connection, parse the upstream HTTP/1.1 response, and relay it back to the client.

Builds on the connection pool infrastructure from #13.

• 14 new files
• 1,580 lines of production code
• 1,719 lines of tests
• 12 modified files
• +385 lines in modified files

What’s new

Proxy engine (ProxyHandler → ProxyTransaction)

• Per-upstream ProxyHandler

  • Stateless factory created once at Start()
  • Registered as async routes via RouteAsync

• Per-request ProxyTransaction

  • State machine:
    • INIT
    • CHECKOUT_PENDING
    • SENDING_REQUEST
    • AWAITING_RESPONSE
    • RECEIVING_BODY
    • COMPLETE
  • Orchestrates the full proxy lifecycle
  • Uses shared_from_this() self-capture for async safety

• Config-driven auto-registration

  • Upstreams with a proxy section auto-register routes at startup
  • Manual HttpServer::Proxy() API is also available

• HTTP/2 downstream transparent

  • Async handler API (AsyncCompletionCallback) handles H1/H2 delivery
  • ProxyTransaction is protocol-agnostic

Foundation components

• UpstreamHttpCodec

  • llhttp in HTTP_RESPONSE mode
  • Explicit 1xx interim response handling (resume + discard loop)
  • 64MB body cap
  • Repeated header preservation via vector<pair<...>>

• HttpRequestSerializer

  • Stateless HTTP/1.1 wire format serializer
  • Preserves query strings

• HeaderRewriter

  • RFC 7230 §6.1 hop-by-hop header removal
  • X-Forwarded-For append
  • X-Forwarded-Proto
  • Via
  • Configurable Host rewrite
  • Strips headers listed in Connection

• RetryPolicy

  • Idempotency-aware retry
  • Configurable retry conditions:
    • connect failure
    • 5xx
    • timeout
    • disconnect
  • Jittered exponential backoff

Infrastructure changes

• HttpRequest

  • Added peer metadata fields:
    • client_ip
    • client_tls
    • client_fd
  • Populated on both H1 and H2 dispatch paths

• HttpResponse

  • Added BadGateway() and GatewayTimeout() factory methods

• PoolPartition::ReturnConnection

  • Added IsClosing() check
  • Destroys early-response-poisoned connections instead of returning them to idle
  • Prevents write buffer corruption

• ProxyConfig

  • Full config schema:
    • route_prefix
    • strip_prefix
    • methods
    • response_timeout_ms
    • header_rewrite
    • retry
  • Parsing, validation, and serialization added in ConfigLoader

New files (14)

Modified files

Note: one summary lists 10 modified files, while the pasted implementation summary reports 12 modified files overall.

Key design decisions

Configuration example

{
  "upstreams": [{
    "name": "user-service",
    "host": "10.0.1.10",
    "port": 8081,
    "pool": { "max_connections": 64 },
    "proxy": {
      "route_prefix": "/api/users",
      "strip_prefix": true,
      "methods": ["GET", "POST", "PUT", "DELETE"],
      "response_timeout_ms": 30000,
      "header_rewrite": {
        "set_x_forwarded_for": true,
        "rewrite_host": true
      },
      "retry": {
        "max_retries": 1,
        "retry_on_connect_failure": true
      }
    }
  }]
}

Error mapping

Test plan

50 new tests in test/proxy_test.h (./test_runner proxy / -P):

• Unit tests (39)

  • UpstreamHttpCodec (11)
    • includes 1xx handling
    • repeated headers
    • 64MB cap
  • HttpRequestSerializer (5)
  • HeaderRewriter (8)
  • RetryPolicy (9)
  • ProxyConfig parsing (6)

• Integration tests (11)

  • GET/POST proxy with real upstream servers
  • header rewriting
  • 502/504 error paths
  • strip_prefix
  • query string forwarding
  • connection reuse
  • early-response pool safety

Validation

• All 302 tests pass
  • 252 existing
  • 50 new
• Two consecutive runs stable